home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kontact / plugin.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-02-13  |  7.8 KB  |  292 lines
  1. /*
  2.    This file is part of KDE Kontact.
  3.  
  4.    Copyright (c) 2001 Matthias Hoelzer-Kluepfel <mhk@kde.org>
  5.    Copyright (c) 2002-2003 Daniel Molkentin <molkentin@kde.org>
  6.    Copyright (c) 2003 Cornelius Schumacher <schumacher@kde.org>
  7.  
  8.    This library is free software; you can redistribute it and/or
  9.    modify it under the terms of the GNU Library General Public
  10.    License as published by the Free Software Foundation; either
  11.    version 2 of the License, or (at your option) any later version.
  12.  
  13.    This library is distributed in the hope that it will be useful,
  14.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16.    Library General Public License for more details.
  17.  
  18.    You should have received a copy of the GNU Library General Public License
  19.    along with this library; see the file COPYING.LIB.  If not, write to
  20.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  21.    Boston, MA 02110-1301, USA.
  22. */
  23.  
  24. #ifndef KONTACT_PLUGIN_H
  25. #define KONTACT_PLUGIN_H
  26.  
  27. #include <qobject.h>
  28. #include <kxmlguiclient.h>
  29. #include <kdepimmacros.h>
  30. #include <qptrlist.h>
  31.  
  32. class QStringList;
  33. class DCOPClient;
  34. class DCOPObject;
  35. class KAboutData;
  36. class KAction;
  37. class KConfig;
  38. class QWidget;
  39. namespace KParts { class ReadOnlyPart; }
  40.  
  41. /**
  42.   Increase this version number whenever you make a change
  43.   in the API.
  44.  */
  45. #define KONTACT_PLUGIN_VERSION 6
  46.  
  47. namespace Kontact
  48. {
  49.  
  50. class Core;
  51. class Summary;
  52.  
  53. /**
  54.   Base class for all Plugins in Kontact. Inherit from it
  55.   to get a plugin. It can insert an icon into the sidepane,
  56.   add widgets to the widgetstack and add menu items via XMLGUI.
  57.  */
  58. class KDE_EXPORT Plugin : public QObject, virtual public KXMLGUIClient
  59. {
  60.   Q_OBJECT
  61.  
  62.   public:
  63.     /**
  64.       Creates a new Plugin, note that name parameter name is required if
  65.       you want your plugin to do dcop via it's own instance of
  66.       DCOPClient by calling dcopClient.
  67.       @note name MUST be the name of the application that
  68.       provides the part! This is the name used for DCOP registration.
  69.       It's ok to have several plugins using the same application name.
  70.     */
  71.     Plugin( Core *core, QObject *parent, const char *name );
  72.  
  73.     ~Plugin();
  74.  
  75.     /**
  76.       Sets the identifier.
  77.     */
  78.     void setIdentifier( const QString &identifier );
  79.  
  80.     /**
  81.       Returns the identifier. It is used as argument for several
  82.       methods of Kontacts core.
  83.     */
  84.     QString identifier() const;
  85.  
  86.     /**
  87.       Sets the localized title.
  88.      */
  89.     void setTitle( const QString &title );
  90.  
  91.     /**
  92.       Returns the localized title.
  93.     */
  94.     QString title() const;
  95.  
  96.     /**
  97.       Sets the icon name.
  98.     */
  99.     void setIcon( const QString &icon );
  100.  
  101.     /**
  102.       Returns the icon name.
  103.     */
  104.     QString icon() const;
  105.  
  106.     /**
  107.       Sets the name of executable (if existant).
  108.     */
  109.     void setExecutableName( const QString &bin );
  110.  
  111.     /**
  112.       Returns the name of the binary (if existant).
  113.     */
  114.     QString executableName() const;
  115.  
  116.     /**
  117.       Set name of library which contains the KPart used by this plugin.
  118.     */
  119.     void setPartLibraryName( const QCString & );
  120.  
  121.     /**
  122.       Create the DCOP interface for the given @p serviceType, if this
  123.       plugin provides it. Return false otherwise.
  124.     */
  125.     virtual bool createDCOPInterface( const QString& /*serviceType*/ ) { return false; }
  126.  
  127.     /**
  128.       Reimplement this method and return wether a standalone application is still running
  129.       This is only required if your part is also available as standalone application.
  130.     */
  131.     virtual bool isRunningStandalone() { return false; }
  132.  
  133.     /**
  134.       Reimplement this method if your application needs a different approach to be brought
  135.       in the foreground. The default behaviour is calling the binary.
  136.       This is only required if your part is also available as standalone application.
  137.     */
  138.     virtual void bringToForeground();
  139.  
  140.     /**
  141.       Reimplement this method if you want to add your credits to the Kontact
  142.       about dialog.
  143.     */
  144.     virtual const KAboutData *aboutData();
  145.  
  146.     /**
  147.       You can use this method if you need to access the current part. You can be
  148.       sure that you always get the same pointer as long as the part has not been
  149.       deleted.
  150.     */
  151.     KParts::ReadOnlyPart *part();
  152.  
  153.      /**
  154.        Reimplement this method and return the a path relative to "data" to the tips file.
  155.      */
  156.     virtual QString tipFile() const;
  157.  
  158.     /**
  159.       This function is called when the plugin is selected by the user before the
  160.       widget of the KPart belonging to the plugin is raised.
  161.     */
  162.     virtual void select();
  163.  
  164.     /**
  165.       This function is called whenever the config dialog has been closed
  166.       successfully.
  167.      */
  168.     virtual void configUpdated();
  169.  
  170.     /**
  171.       Reimplement this method if you want to add a widget for your application
  172.       to Kontact's summary page.
  173.     */
  174.     virtual Summary *createSummaryWidget( QWidget * /*parent*/ ) { return 0; }
  175.  
  176.     /**
  177.       Returns wether the plugin provides a part that should be shown in the sidebar.
  178.     */
  179.     virtual bool showInSideBar() const;
  180.  
  181.     /**
  182.       Set if the plugin provides a part that should be shown in the sidebar.
  183.     */
  184.     void setShowInSideBar( bool hasPart );
  185.  
  186.     /**
  187.       Reimplement this method if you want to add checks before closing down the main kontact
  188.       window.  Return true if it's OK to close the window.  If any loaded plugin returns false
  189.       from this method, then the main kontact window will not close.
  190.     */
  191.     virtual bool queryClose() const { return true; }
  192.  
  193.     /**
  194.       Retrieve the current DCOP Client for the plugin.
  195.  
  196.       The clients name is taken from the name argument in the constructor.
  197.       @note: The DCOPClient object will only be created when this method is
  198.       called for the first time. Make sure that the part has been loaded
  199.       before calling this method, if it's the one that contains the DCOP
  200.       interface that other parts might use.
  201.     */
  202.     DCOPClient *dcopClient() const;
  203.  
  204.     /**
  205.       Return the weight of the plugin. The higher the weight the lower it will
  206.       be displayed in the sidebar. The default implementation returns 0.
  207.     */
  208.     virtual int weight() const { return 0; }
  209.  
  210.     /**
  211.       Insert "New" action.
  212.     */
  213.     void insertNewAction( KAction *action );
  214.  
  215.     /**
  216.       Insert "Sync" action.
  217.     */
  218.     void insertSyncAction( KAction *action );
  219.  
  220.     /**
  221.       FIXME: write API doc for Kontact::Plugin::newActions().
  222.     */
  223.     QPtrList<KAction>* newActions() const;
  224.  
  225.     /**
  226.       FIXME: write API doc for Kontact::Plugin::syncActions().
  227.     */
  228.     QPtrList<KAction>* syncActions() const;
  229.  
  230.     /**
  231.       Returns a list of action name which shall be hidden in the main toolbar.
  232.      */
  233.     virtual QStringList invisibleToolbarActions() const { return QStringList(); }
  234.  
  235.     /**
  236.       Return, if the plugin can handle the drag object of the given mime type.
  237.     */
  238.     virtual bool canDecodeDrag( QMimeSource * ) { return false; }
  239.  
  240.     /**
  241.       Process drop event.
  242.     */
  243.     virtual void processDropEvent( QDropEvent * ) {}
  244.  
  245.     virtual void loadProfile( const QString& directoryPath );
  246.  
  247.     virtual void saveToProfile( const QString& directoryPath ) const;
  248.  
  249.     /**
  250.      * Session management: read properties
  251.      */
  252.     virtual void readProperties( KConfig * ) {}
  253.  
  254.     /**
  255.      * Session management: save properties
  256.      */
  257.     virtual void saveProperties( KConfig * ) {}
  258.  
  259.     Core *core() const;
  260.  
  261.     bool disabled() const;
  262.     void setDisabled( bool v );
  263.  
  264.   public slots:
  265.     /**
  266.       internal usage
  267.      */
  268.     void slotConfigUpdated();
  269.  
  270.   protected:
  271.     /**
  272.       Reimplement and return the part here. Reimplementing createPart() is
  273.       mandatory!
  274.     */
  275.     virtual KParts::ReadOnlyPart *createPart() = 0;
  276.  
  277.     KParts::ReadOnlyPart *loadPart();
  278.  
  279.     virtual void virtual_hook(  int id, void* data );
  280.  
  281.   private slots:
  282.     void partDestroyed();
  283.  
  284.   private:
  285.     class Private;
  286.     Private *d;
  287. };
  288.  
  289. }
  290.  
  291. #endif
  292.